refactor(cli)!: unify naming without backward-compat aliases by jesseturner21 · Pull Request #705 · aws/agentcore-cli

jesseturner21 · 2026-03-27T16:22:46Z

Summary

BREAKING CHANGE — Same naming unification as #702 but without backward-compatibility aliases.

add identity → add credential: No identity alias. Old command stops working.
--force removed from remove: Only -y, --yes works. No --force alias.
--plan removed from deploy: Only --dry-run works. No --plan alias.

This is the clean-break alternative to #702 (which preserves aliases). Choose one to merge.

Changes from #702

The first 4 commits are cherry-picked from #702 (credential rename, --yes standardization, --dry-run standardization, article fix). The final commit removes all aliases:

Removed .alias('identity') from credential command
Removed --force option from BasePrimitive.registerRemoveSubcommand() and remove all
Removed --plan option from deploy
Updated tests to use --yes instead of --force

Testing

All 3076 unit tests pass (npm test)
TypeScript build succeeds (tsc --noEmit)
ESLint + Prettier pass via pre-commit hooks
agentcore add --help shows only credential (no identity alias)
agentcore deploy --help shows only --dry-run (no --plan)
agentcore remove agent --help shows only -y, --yes (no --force)

Test plan

npm test — all 3076 tests pass
tsc --noEmit — clean typecheck
Pre-commit hooks pass on all commits
CLI help text shows only canonical flag names (no aliases)

The CLI command was 'add identity', the config key was 'credentials', and the resource types were ApiKeyCredentialProvider / OAuthCredentialProvider. Three different names for the same concept. This unifies everything under 'credential' — CLI commands, resource type, labels, validation, and docs. The old 'identity' command name is preserved as a hidden alias for backward compatibility. Constraint: Must maintain backward compat for existing scripts using 'agentcore add identity' Rejected: Keep 'identity' as primary | 'credential' is already the config term and more precise Confidence: high Scope-risk: moderate

deploy uses -y, --yes while remove uses --force. These mean the same thing (skip interactive confirmation) but used different names. Now -y/--yes is the primary flag everywhere. --force is preserved as an alias on remove commands for backward compatibility. Constraint: Must not break existing scripts using --force on remove Rejected: Use --force everywhere | --yes is the conventional flag name for confirmation skip Confidence: high Scope-risk: narrow

deploy uses --plan while create and remove use --dry-run. Same concept, different names. Now --dry-run is the primary flag on deploy. --plan is preserved as an alias for backward compatibility. Output message updated from 'Plan complete' to 'Dry run complete'. Constraint: Must not break existing scripts using --plan on deploy Rejected: Use --plan everywhere | --dry-run is the standard convention Confidence: high Scope-risk: narrow

The article was 'an' for the old 'identity' label but 'credential' takes 'a'. This fixes help text like "Remove an credential" → "Remove a credential". Confidence: high Scope-risk: narrow

BREAKING CHANGE: Remove all backward-compatibility aliases: - `agentcore add identity` no longer works (use `agentcore add credential`) - `--force` flag removed from remove commands (use `-y` or `--yes`) - `--plan` flag removed from deploy command (use `--dry-run`) This is the clean-break alternative to the alias-preserving PR. Confidence: high Scope-risk: moderate

The --plan alias was removed in the breaking change commit. Confidence: high Scope-risk: narrow

…emoval Integration tests were still using `add identity` and `remove identity` commands which no longer exist without the backward-compat aliases. Confidence: high Scope-risk: narrow

Hweinstock

LGTM!

when reading this, credential sounded slightly strange instead of credentials, but I guess its correct since we're referring to a single instance of credentials? I'm aligned if we think singular makes sense.

github-actions · 2026-03-27T16:42:00Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	45.81%	6486 / 14158
🔵	Statements	45.37%	6889 / 15181
🔵	Functions	44.37%	1159 / 2612
🔵	Branches	45.91%	4273 / 9306

Generated in workflow #1438 for commit 6e56498 by the Vitest Coverage Report Action

- Remove `type` fields from agent, memory, evaluator, online-eval-config examples and field tables (removed in aws#709) - Remove `modelProvider` from agent spec (removed in aws#709) - Rename credential `type` to `authorizerType` (renamed in aws#709) - Rename `add identity` to `add credential` everywhere (aws#705) - Replace `--force` with `-y/--yes` on remove commands (aws#705) - Replace `--plan` with `--dry-run` on deploy command (aws#705) - Update snapshot for src/assets/README.md change

- Rename --agent-client-id → --client-id, --agent-client-secret → --client-secret in gateway docs (naming unification aws#705) - Add missing flags to add agent: --authorizer-type, --discovery-url, --allowed-audience, --allowed-clients, --allowed-scopes, --custom-claims, --client-id, --client-secret, --idle-timeout, --max-lifetime - Add missing flags to create: --idle-timeout, --max-lifetime - Add missing flags to add gateway: --runtimes, --custom-claims, --policy-engine, --policy-engine-mode - Fix --exception-level values: NONE/ALL (was undocumented) Confidence: high Scope-risk: narrow

- Remove `type` fields from agent, memory, evaluator, online-eval-config examples and field tables (removed in aws#709) - Remove `modelProvider` from agent spec (removed in aws#709) - Rename credential `type` to `authorizerType` (renamed in aws#709) - Rename `add identity` to `add credential` everywhere (aws#705) - Replace `--force` with `-y/--yes` on remove commands (aws#705) - Replace `--plan` with `--dry-run` on deploy command (aws#705) - Update snapshot for src/assets/README.md change

- Rename --agent-client-id → --client-id, --agent-client-secret → --client-secret in gateway docs (naming unification aws#705) - Add missing flags to add agent: --authorizer-type, --discovery-url, --allowed-audience, --allowed-clients, --allowed-scopes, --custom-claims, --client-id, --client-secret, --idle-timeout, --max-lifetime - Add missing flags to create: --idle-timeout, --max-lifetime - Add missing flags to add gateway: --runtimes, --custom-claims, --policy-engine, --policy-engine-mode - Fix --exception-level values: NONE/ALL (was undocumented) Confidence: high Scope-risk: narrow

- Remove `type` fields from agent, memory, evaluator, online-eval-config examples and field tables (removed in aws#709) - Remove `modelProvider` from agent spec (removed in aws#709) - Rename credential `type` to `authorizerType` (renamed in aws#709) - Rename `add identity` to `add credential` everywhere (aws#705) - Replace `--force` with `-y/--yes` on remove commands (aws#705) - Replace `--plan` with `--dry-run` on deploy command (aws#705) - Update snapshot for src/assets/README.md change

- Rename --agent-client-id → --client-id, --agent-client-secret → --client-secret in gateway docs (naming unification aws#705) - Add missing flags to add agent: --authorizer-type, --discovery-url, --allowed-audience, --allowed-clients, --allowed-scopes, --custom-claims, --client-id, --client-secret, --idle-timeout, --max-lifetime - Add missing flags to create: --idle-timeout, --max-lifetime - Add missing flags to add gateway: --runtimes, --custom-claims, --policy-engine, --policy-engine-mode - Fix --exception-level values: NONE/ALL (was undocumented) Confidence: high Scope-risk: narrow

) * docs: fix 30 documentation inaccuracies found by source code audit - configuration.md: fix networkMode PRIVATE→VPC, remove stale mcp.json section, add 7 missing AgentEnvSpec fields, add Node.js runtimes, fix gateway name max 63→100, list all 6 targetType values, fix memory strategies wording, fix deployed-state.json path, add missing project fields, fix CUSTOM_JWT field requirements, add customClaims field - README.md: add CrewAI framework, update all 4 default model IDs, add missing command sections - frameworks.md: add CrewAI with model providers, add protocol compatibility matrix (HTTP/MCP/A2A) - commands.md: fix agent name max 64→48 chars, add fetch access section, add policy-engine/policy to status --type, remove ghost --tool-filter-description flag, fix model ID date - gateway.md: add enableSemanticSearch/exceptionLevel config options, fix mcp.json→agentcore.json, remove api-key from MCP Server auth - transaction_search.md: fix traces command syntax - container-builds.md: remove nonexistent --progress flag - evals.md: fix model date 20250929→20250514 - local-development.md: fix mcp.json→agentcore.json - AGENTS.md: remove AutoGen, remove stale mcp.json reference - src/assets/README.md: add CrewAI to template list - src/assets/agents/AGENTS.md: remove AutoGen Constraint: All fixes verified against Zod schemas and CLI runtime Constraint: CLI --help text bugs left for separate agent Confidence: high Scope-risk: narrow * style: run prettier on documentation files * test: update asset snapshots for edited README.md and AGENTS.md * ci: trigger build workflow * docs: update docs for upstream schema refactor and naming unification - Remove `type` fields from agent, memory, evaluator, online-eval-config examples and field tables (removed in #709) - Remove `modelProvider` from agent spec (removed in #709) - Rename credential `type` to `authorizerType` (renamed in #709) - Rename `add identity` to `add credential` everywhere (#705) - Replace `--force` with `-y/--yes` on remove commands (#705) - Replace `--plan` with `--dry-run` on deploy command (#705) - Update snapshot for src/assets/README.md change * docs: fix stale agents reference in gateway example Update `"agents": [...]` to `"runtimes": [...]` in the gateway configuration example to match the schema rename in #706. * docs: rename --agent flags to --runtime and remove stale type fields Update all documentation to reflect upstream renames: - --agent → --runtime, -a → -r across all commands - --agent-arn → --runtime-arn, --agent-runtime-id → --runtime-id - Remove stale "type" fields from JSON examples in evals.md, memory.md, and container-builds.md Constraint: --agent-id, --agent-alias-id, --agent-client-id, --agent-client-secret are unchanged (different semantics) Constraint: --type agent filter value in status/fetch stays as-is Confidence: high Scope-risk: narrow * docs: add missing flags and fix --lines → --limit - Add -H, --header flag to dev and invoke commands - Add --bearer-token flag to invoke command - Fix --lines → --limit in evals.md logs evals section Confidence: high Scope-risk: narrow * docs: fix stale gateway flags and add missing CLI flags - Rename --agent-client-id → --client-id, --agent-client-secret → --client-secret in gateway docs (naming unification #705) - Add missing flags to add agent: --authorizer-type, --discovery-url, --allowed-audience, --allowed-clients, --allowed-scopes, --custom-claims, --client-id, --client-secret, --idle-timeout, --max-lifetime - Add missing flags to create: --idle-timeout, --max-lifetime - Add missing flags to add gateway: --runtimes, --custom-claims, --policy-engine, --policy-engine-mode - Fix --exception-level values: NONE/ALL (was undocumented) Confidence: high Scope-risk: narrow * docs: fix --exception-level valid values to NONE/DEBUG The CLI help text says ALL but the schema (GatewayExceptionLevelSchema) defines the valid values as NONE and DEBUG. Aligns commands.md with gateway.md and the Zod schema. * docs: fix stale fields and add flags from upstream v0.5–v0.7 - Remove stale "type": "AgentCoreMemory" from memory streaming example - Add memory streaming flags: --delivery-type, --data-stream-arn, --stream-content-level, --stream-delivery-resources - Add --exec to dev command flag table (Container agents) - Add --skip-install to create command flag table - Add --identity-name to fetch access flag table

jesseturner21 added 5 commits March 27, 2026 16:17

fix(cli): correct article for credential primitive ('a' not 'an')

e476740

The article was 'an' for the old 'identity' label but 'credential' takes 'a'. This fixes help text like "Remove an credential" → "Remove a credential". Confidence: high Scope-risk: narrow

jesseturner21 requested a review from a team March 27, 2026 16:22

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 16:22 — with GitHub Actions Failure

github-actions Bot added the size/m PR size: M label Mar 27, 2026

fix(test): update deploy help test to check --dry-run instead of --plan

11dfe66

The --plan alias was removed in the breaking change commit. Confidence: high Scope-risk: narrow

github-actions Bot added size/m PR size: M and removed size/m PR size: M labels Mar 27, 2026

fix(test): update integration tests for credential rename and alias r…

97eb9cd

…emoval Integration tests were still using `add identity` and `remove identity` commands which no longer exist without the backward-compat aliases. Confidence: high Scope-risk: narrow

github-actions Bot added size/m PR size: M and removed size/m PR size: M labels Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 16:36 — with GitHub Actions Failure

Hweinstock previously approved these changes Mar 27, 2026

View reviewed changes

Comment thread src/cli/primitives/CredentialPrimitive.tsx

Merge branch 'main' into refactor/unify-cli-naming-breaking

6e56498

jesseturner21 dismissed Hweinstock’s stale review via 6e56498 March 27, 2026 17:09

github-actions Bot removed the size/m PR size: M label Mar 27, 2026

jesseturner21 had a problem deploying to e2e-testing March 27, 2026 17:09 — with GitHub Actions Failure

github-actions Bot added the size/m PR size: M label Mar 27, 2026

aidandaly24 approved these changes Mar 27, 2026

View reviewed changes

jesseturner21 merged commit 5e55ea5 into main Mar 27, 2026
19 of 21 checks passed

jesseturner21 deleted the refactor/unify-cli-naming-breaking branch March 27, 2026 17:12

aidandaly24 mentioned this pull request Mar 28, 2026

docs: fix 30 documentation inaccuracies found by source code audit #697

Merged

15 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(cli)!: unify naming without backward-compat aliases#705

refactor(cli)!: unify naming without backward-compat aliases#705
jesseturner21 merged 8 commits intomainfrom
refactor/unify-cli-naming-breaking

jesseturner21 commented Mar 27, 2026

Uh oh!

Hweinstock left a comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jesseturner21 commented Mar 27, 2026

Summary

Changes from #702

Testing

Test plan

Uh oh!

Hweinstock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Mar 27, 2026 •

edited

Loading